Docusaurus
Docusaurus는 Meta(구 Facebook)에서 개발한 React 기반의 오픈 소스 정적 사이트 생성기(SSG, Static Site Generator)로, 주로 기술 문서 사이트를 구축하기 위해 최적화된 도구입니다. 특히 개발자 문서(Developer Documentation) 구축에 특화되어 있어, 일반적인 블로그용 SSG와 차별화되는 강력한 문서화 기능을 제공합니다.
1. 개요
Docusaurus는 개발자가 Markdown 파일을 통해 쉽고 빠르게 전문적인 문서 사이트를 구축할 수 있도록 돕는 프레임워크입니다. 정적 사이트 생성기(SSG)란 서버 측에서 실시간으로 페이지를 생성하는 대신, 빌드 타임에 미리 HTML 파일을 생성하여 웹 서버에 배포하는 방식을 의미합니다. 이를 통해 매우 빠른 페이지 로딩 속도와 높은 보안성을 제공하며, Meta의 React 생태계를 활용하여 단순한 문서 페이지를 넘어 인터랙티브한 웹 애플리케이션 수준의 기능을 구현할 수 있습니다.
2. 주요 특징 및 장점
Docusaurus는 문서화에 필요한 핵심 기능들을 기본적으로 내장하고 있어, 별도의 복잡한 설정 없이도 기업 수준의 문서 사이트를 구축할 수 있습니다.
- React 기반의 유연성: 모든 페이지가 React 컴포넌트로 변환되므로, 필요에 따라 사용자 정의 UI 컴포넌트를 직접 제작하여 삽입할 수 있습니다.
- Markdown 및 MDX 지원: 표준 Markdown뿐만 아니라 MDX(Markdown + JSX)를 지원합니다. MDX는 마크다운 문서 내에서 React 컴포넌트를 직접 사용할 수 있게 해주는 확장 문법입니다.
- 강력한 검색 및 다국어 지원: Algolia DocSearch와의 통합을 통해 고성능 검색 기능을 제공하며, i18n(Internationalization) 설정을 통해 다국어 사이트를 손쉽게 운영할 수 있습니다.
- SEO 최적화: 정적 HTML로 빌드되므로 검색 엔진 최적화(SEO)에 유리하며, 메타 태그 및 사이트맵 생성 기능을 기본 제공합니다.
타 SSG 도구와의 비교
| 특징 |
Docusaurus |
Hugo |
Jekyll |
GitBook |
| 기반 언어 |
React (JS/TS) |
Go |
Ruby |
Proprietary/JS |
| 주요 목적 |
기술 문서화 |
범용 블로그/사이트 |
범용 블로그/사이트 |
기업용 위키/문서 |
| 학습 곡선 |
낮음 ~ 중간 (커스터마이징 시 React 필요) |
낮음 |
낮음 |
매우 낮음 |
| 확장성 |
매우 높음 (MDX) |
높음 |
중간 |
낮음 (플랜 제한) |
| 빌드 속도 |
보통 |
매우 빠름 |
보통 |
N/A (SaaS) |
3. 핵심 아키텍처 및 작동 원리
Docusaurus는 '빌드 타임 정적 생성'과 '런타임 클라이언트 사이드 렌더링(CSR)'의 하이브리드 방식을 채택하고 있습니다.
- 변환 단계: 사용자가 작성한
.md 또는 .mdx 파일이 빌드 프로세스를 통해 React 컴포넌트로 변환됩니다.
- 정적 빌드: 변환된 컴포넌트들은 Node.js 환경에서 미리 렌더링되어 정적인 HTML 파일로 출력됩니다. 이 과정에서 사이드바 구조, 내비게이션 바 등이 함께 생성됩니다.
- 하이드레이션(Hydration): 브라우저가 HTML을 로드한 후, React가 실행되면서 정적 HTML 위에 동적인 이벤트 리스너와 상태 관리를 입히는 '하이드레이션' 과정이 일어납니다. 이를 통해 사용자는 정적 페이지의 속도와 SPA(Single Page Application)의 부드러운 전환 효과를 동시에 경험하게 됩니다.
4. 설치 및 기본 설정
Docusaurus를 사용하기 위해서는 Node.js(v18.0 이상 권장) 환경이 필요합니다.
퀵스타트 가이드 (Quick Start)
터미널에서 아래 명령어를 입력하여 프로젝트를 즉시 생성하고 실행할 수 있습니다.
# 1. 프로젝트 생성 (my-website 부분에 원하는 폴더명 입력)
npx create-docusaurus@latest my-website classic
# 2. 프로젝트 폴더로 이동
cd my-website
# 3. 로컬 개발 서버 실행
npm start
실행 후 브라우저에서
http://localhost:3000에 접속하면 기본 템플릿 사이트를 확인할 수 있습니다.
기본 폴더 구조
/docs: 실제 문서 파일(.md, .mdx)이 저장되는 곳입니다. 파일 구조가 그대로 사이드바에 반영됩니다./blog: 블로그 포스트를 작성하는 공간입니다./src: 사용자 정의 React 컴포넌트, CSS 스타일, 페이지 레이아웃 등이 위치합니다./static: 이미지, 폰트 등 정적 파일이 저장되며, / 경로로 직접 접근 가능합니다.docusaurus.config.js: 사이트 제목, URL, 내비게이션 바, 플러그인 설정 등 전체 설정을 관리하는 핵심 파일입니다.sidebars.json: 문서의 계층 구조와 표시 순서를 정의하는 설정 파일입니다.
5. 주요 기능 활용법
소프트웨어의 버전 업데이트에 따라 문서도 함께 관리해야 할 때 유용합니다. docusaurus version 명령어를 통해 현재 상태의 문서를 스냅샷으로 저장하고, 사용자가 상단 드롭다운 메뉴에서 특정 버전의 문서를 선택해 볼 수 있게 합니다.
MDX를 활용한 인터랙티브 컴포넌트
단순 텍스트 외에 버튼, 탭, 경고창 등 동적인 요소를 문서에 삽입할 수 있습니다.
import MyCustomButton from '@site/src/components/MyCustomButton';
# 안녕하세요!
이것은 일반 마크다운 텍스트입니다. 아래는 React 컴포넌트입니다.
<MyCustomButton color="blue">클릭하세요!</MyCustomButton>
참고: @site는 프로젝트 루트 디렉토리를 가리키는 Docusaurus 전용 별칭(Alias)입니다.
테마 및 플러그인 확장
docusaurus.config.js 파일의 plugins 배열에 필요한 플러그인을 추가하여 기능을 확장할 수 있습니다. 예를 들어, 검색 기능을 위한 Algolia 플러그인이나 사이트맵 생성 플러그인을 추가하여 운영 효율을 높일 수 있습니다. 또한, CSS 변수를 수정하여 브랜드 컬러를 변경하거나, src/css/custom.css를 통해 세부 디자인을 커스터마이징하여 브랜드 아이덴티티가 반영된 독자적인 테마를 구축할 수 있습니다.
6. 배포 및 운영
작성 완료된 사이트는 정적 파일로 빌드하여 어디든 배포할 수 있습니다.
빌드 프로세스
# 정적 파일 생성 (build 폴더에 HTML/JS/CSS 생성)
npm run build
대부분의 정적 호스팅 서비스는 GitHub 저장소와 연동하여 자동 배포를 지원합니다.
* Vercel / Netlify: 저장소 연결 후 빌드 명령어(npm run build)와 출력 디렉토리(build)만 설정하면 푸시할 때마다 자동 배포됩니다.
* GitHub Pages: docusaurus.config.js에 url과 baseUrl을 설정한 후, GitHub Actions 워크플로우를 통해 gh-pages 브랜치로 자동 배포하는 방식을 주로 사용합니다. 이때, 배포 스크립트가 저장소에 접근할 수 있도록 GITHUB_TOKEN이나 DEPLOY_KEY와 같은 환경 변수 설정이 필요합니다.
7. 실제 구축 사례 및 레퍼런스
많은 글로벌 오픈 소스 프로젝트와 기업들이 Docusaurus를 사용하여 기술 문서를 운영하고 있습니다.
- React 공식 문서: Docusaurus의 철학이 가장 잘 반영된 사례입니다.
- Algolia: 검색 엔진 서비스 Algolia의 방대한 API 문서를 Docusaurus로 구축하였습니다.
- Meta Open Source: Meta의 다양한 오픈 소스 프로젝트 문서화에 표준으로 사용됩니다.
8. 변경 로그 (Change Log)
Docusaurus는 지속적인 업데이트를 통해 기능을 개선하고 있습니다.
| 버전 |
주요 변경 사항 |
비고 |
| v3.x |
React 18 지원, 성능 최적화, MDX 3.0 도입 |
최신 안정 버전 |
| v2.x |
버전 관리 기능 강화, 다국어 지원(i18n) 고도화, 플러그인 시스템 정립 |
장기 지원 버전 |
| v1.x |
초기 프레임워크 구조 확립, 기본 Markdown 렌더링 지원 |
레거시 버전 |
외부 링크
# Docusaurus
Docusaurus는 Meta(구 Facebook)에서 개발한 React 기반의 오픈 소스 정적 사이트 생성기(SSG, Static Site Generator)로, 주로 기술 문서 사이트를 구축하기 위해 최적화된 도구입니다. 특히 개발자 문서(Developer Documentation) 구축에 특화되어 있어, 일반적인 블로그용 SSG와 차별화되는 강력한 문서화 기능을 제공합니다.
## 1. 개요
Docusaurus는 개발자가 Markdown 파일을 통해 쉽고 빠르게 전문적인 문서 사이트를 구축할 수 있도록 돕는 프레임워크입니다. 정적 사이트 생성기(SSG)란 서버 측에서 실시간으로 페이지를 생성하는 대신, 빌드 타임에 미리 HTML 파일을 생성하여 웹 서버에 배포하는 방식을 의미합니다. 이를 통해 매우 빠른 페이지 로딩 속도와 높은 보안성을 제공하며, Meta의 React 생태계를 활용하여 단순한 문서 페이지를 넘어 인터랙티브한 웹 애플리케이션 수준의 기능을 구현할 수 있습니다.
## 2. 주요 특징 및 장점
Docusaurus는 문서화에 필요한 핵심 기능들을 기본적으로 내장하고 있어, 별도의 복잡한 설정 없이도 기업 수준의 문서 사이트를 구축할 수 있습니다.
* **React 기반의 유연성**: 모든 페이지가 React 컴포넌트로 변환되므로, 필요에 따라 사용자 정의 UI 컴포넌트를 직접 제작하여 삽입할 수 있습니다.
* **Markdown 및 MDX 지원**: 표준 Markdown뿐만 아니라 **MDX**(Markdown + JSX)를 지원합니다. MDX는 마크다운 문서 내에서 React 컴포넌트를 직접 사용할 수 있게 해주는 확장 문법입니다.
* **강력한 검색 및 다국어 지원**: Algolia DocSearch와의 통합을 통해 고성능 검색 기능을 제공하며, i18n(Internationalization) 설정을 통해 다국어 사이트를 손쉽게 운영할 수 있습니다.
* **SEO 최적화**: 정적 HTML로 빌드되므로 검색 엔진 최적화(SEO)에 유리하며, 메타 태그 및 사이트맵 생성 기능을 기본 제공합니다.
### 타 SSG 도구와의 비교
| 특징 | Docusaurus | Hugo | Jekyll | GitBook |
| :--- | :--- | :--- | :--- | :--- |
| **기반 언어** | React (JS/TS) | Go | Ruby | Proprietary/JS |
| **주요 목적** | 기술 문서화 | 범용 블로그/사이트 | 범용 블로그/사이트 | 기업용 위키/문서 |
| **학습 곡선** | 낮음 ~ 중간 (커스터마이징 시 React 필요) | 낮음 | 낮음 | 매우 낮음 |
| **확장성** | 매우 높음 (MDX) | 높음 | 중간 | 낮음 (플랜 제한) |
| **빌드 속도** | 보통 | 매우 빠름 | 보통 | N/A (SaaS) |
## 3. 핵심 아키텍처 및 작동 원리
Docusaurus는 **'빌드 타임 정적 생성'**과 **'런타임 클라이언트 사이드 렌더링(CSR)'**의 하이브리드 방식을 채택하고 있습니다.
1. **변환 단계**: 사용자가 작성한 `.md` 또는 `.mdx` 파일이 빌드 프로세스를 통해 React 컴포넌트로 변환됩니다.
2. **정적 빌드**: 변환된 컴포넌트들은 Node.js 환경에서 미리 렌더링되어 정적인 HTML 파일로 출력됩니다. 이 과정에서 사이드바 구조, 내비게이션 바 등이 함께 생성됩니다.
3. **하이드레이션(Hydration)**: 브라우저가 HTML을 로드한 후, React가 실행되면서 정적 HTML 위에 동적인 이벤트 리스너와 상태 관리를 입히는 '하이드레이션' 과정이 일어납니다. 이를 통해 사용자는 정적 페이지의 속도와 SPA(Single Page Application)의 부드러운 전환 효과를 동시에 경험하게 됩니다.
## 4. 설치 및 기본 설정
Docusaurus를 사용하기 위해서는 Node.js(v18.0 이상 권장) 환경이 필요합니다.
### 퀵스타트 가이드 (Quick Start)
터미널에서 아래 명령어를 입력하여 프로젝트를 즉시 생성하고 실행할 수 있습니다.
```bash
# 1. 프로젝트 생성 (my-website 부분에 원하는 폴더명 입력)
npx create-docusaurus@latest my-website classic
# 2. 프로젝트 폴더로 이동
cd my-website
# 3. 로컬 개발 서버 실행
npm start
```
실행 후 브라우저에서 `http://localhost:3000`에 접속하면 기본 템플릿 사이트를 확인할 수 있습니다.
### 기본 폴더 구조
* `/docs`: 실제 문서 파일(`.md`, `.mdx`)이 저장되는 곳입니다. 파일 구조가 그대로 사이드바에 반영됩니다.
* `/blog`: 블로그 포스트를 작성하는 공간입니다.
* `/src`: 사용자 정의 React 컴포넌트, CSS 스타일, 페이지 레이아웃 등이 위치합니다.
* `/static`: 이미지, 폰트 등 정적 파일이 저장되며, `/` 경로로 직접 접근 가능합니다.
* `docusaurus.config.js`: 사이트 제목, URL, 내비게이션 바, 플러그인 설정 등 전체 설정을 관리하는 핵심 파일입니다.
* `sidebars.json`: 문서의 계층 구조와 표시 순서를 정의하는 설정 파일입니다.
## 5. 주요 기능 활용법
### 문서 버전 관리 (Versioning)
소프트웨어의 버전 업데이트에 따라 문서도 함께 관리해야 할 때 유용합니다. `docusaurus version` 명령어를 통해 현재 상태의 문서를 스냅샷으로 저장하고, 사용자가 상단 드롭다운 메뉴에서 특정 버전의 문서를 선택해 볼 수 있게 합니다.
### MDX를 활용한 인터랙티브 컴포넌트
단순 텍스트 외에 버튼, 탭, 경고창 등 동적인 요소를 문서에 삽입할 수 있습니다.
```jsx
import MyCustomButton from '@site/src/components/MyCustomButton';
# 안녕하세요!
이것은 일반 마크다운 텍스트입니다. 아래는 React 컴포넌트입니다.
<MyCustomButton color="blue">클릭하세요!</MyCustomButton>
```
*참고: `@site`는 프로젝트 루트 디렉토리를 가리키는 Docusaurus 전용 별칭(Alias)입니다.*
### 테마 및 플러그인 확장
`docusaurus.config.js` 파일의 `plugins` 배열에 필요한 플러그인을 추가하여 기능을 확장할 수 있습니다. 예를 들어, 검색 기능을 위한 Algolia 플러그인이나 사이트맵 생성 플러그인을 추가하여 운영 효율을 높일 수 있습니다. 또한, CSS 변수를 수정하여 브랜드 컬러를 변경하거나, `src/css/custom.css`를 통해 세부 디자인을 커스터마이징하여 브랜드 아이덴티티가 반영된 독자적인 테마를 구축할 수 있습니다.
## 6. 배포 및 운영
작성 완료된 사이트는 정적 파일로 빌드하여 어디든 배포할 수 있습니다.
### 빌드 프로세스
```bash
# 정적 파일 생성 (build 폴더에 HTML/JS/CSS 생성)
npm run build
```
### CI/CD 파이프라인 구축
대부분의 정적 호스팅 서비스는 GitHub 저장소와 연동하여 자동 배포를 지원합니다.
* **Vercel / Netlify**: 저장소 연결 후 빌드 명령어(`npm run build`)와 출력 디렉토리(`build`)만 설정하면 푸시할 때마다 자동 배포됩니다.
* **GitHub Pages**: `docusaurus.config.js`에 `url`과 `baseUrl`을 설정한 후, GitHub Actions 워크플로우를 통해 `gh-pages` 브랜치로 자동 배포하는 방식을 주로 사용합니다. 이때, 배포 스크립트가 저장소에 접근할 수 있도록 `GITHUB_TOKEN`이나 `DEPLOY_KEY`와 같은 환경 변수 설정이 필요합니다.
## 7. 실제 구축 사례 및 레퍼런스
많은 글로벌 오픈 소스 프로젝트와 기업들이 Docusaurus를 사용하여 기술 문서를 운영하고 있습니다.
* **React 공식 문서**: Docusaurus의 철학이 가장 잘 반영된 사례입니다.
* **Algolia**: 검색 엔진 서비스 Algolia의 방대한 API 문서를 Docusaurus로 구축하였습니다.
* **Meta Open Source**: Meta의 다양한 오픈 소스 프로젝트 문서화에 표준으로 사용됩니다.
## 8. 변경 로그 (Change Log)
Docusaurus는 지속적인 업데이트를 통해 기능을 개선하고 있습니다.
| 버전 | 주요 변경 사항 | 비고 |
| :--- | :--- | :--- |
| **v3.x** | React 18 지원, 성능 최적화, MDX 3.0 도입 | 최신 안정 버전 |
| **v2.x** | 버전 관리 기능 강화, 다국어 지원(i18n) 고도화, 플러그인 시스템 정립 | 장기 지원 버전 |
| **v1.x** | 초기 프레임워크 구조 확립, 기본 Markdown 렌더링 지원 | 레거시 버전 |
## 외부 링크
* [Docusaurus 공식 문서](https://docusaurus.io/docs)
* [Docusaurus GitHub 저장소](https://github.com/facebook/docusaurus)